<!DOCTYPE HTML PUBLIC "-//ORA//DTD CD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>[Chapter 29] 29.13 java.text.MessageFormat (JDK 1.1)</TITLE>
<META NAME="author" CONTENT="David Flanagan">
<META NAME="date" CONTENT="Thu Jul 31 16:33:13 1997">
<META NAME="form" CONTENT="html">
<META NAME="metadata" CONTENT="dublincore.0.1">
<META NAME="objecttype" CONTENT="book part">
<META NAME="otheragent" CONTENT="gmat dbtohtml">
<META NAME="publisher" CONTENT="O'Reilly &amp; Associates, Inc.">
<META NAME="source" CONTENT="SGML">
<META NAME="subject" CONTENT="Java">
<META NAME="title" CONTENT="Java in a Nutshell">
<META HTTP-EQUIV="Content-Script-Type" CONTENT="text/javascript">
</HEAD>
<body vlink="#551a8b" alink="#ff0000" text="#000000" bgcolor="#FFFFFF" link="#0000ee">

<DIV CLASS=htmlnav>
<H1><a href='index.htm'><IMG SRC="gifs/smbanner.gif"
     ALT="Java in a Nutshell" border=0></a></H1>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch29_12.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><B><FONT FACE="ARIEL,HELVETICA,HELV,SANSERIF" SIZE="-1">Chapter 29<br>The java.text Package</FONT></B></TD>
<td width=172 align=right valign=top><A HREF="ch29_14.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
</table>

&nbsp;
<hr align=left width=515>
</DIV>
<DIV CLASS=sect1>
<h2 CLASS=sect1><A CLASS="TITLE" NAME="JNUT2-CH-29-SECT-13">29.13 java.text.MessageFormat (JDK 1.1)</A></h2>

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JNUT2-CH-29-SECT-13.1"></A></h3>
</DIV>

<P CLASS=para>
This class formats and substitutes objects into specified
positions in a message string (also known as the "pattern"
string).  It provides the closest Java equivalent to the
<tt CLASS=literal>printf()</tt> function of the C programming language.

<P CLASS=para>
If a message is to be displayed only a single time, the
simplest way to use the <tt CLASS=literal>MessageFormat</tt> class is
through the static <tt CLASS=literal>format()</tt> method which is passed
a message or pattern string and an array of argument objects to
be formatted and substituted into the string.  
If the message is to be displayed
several times, it makes more sense to create a
<tt CLASS=literal>MessageFormat</tt> object, supplying the pattern string, 
and then to
call the <tt CLASS=literal>format()</tt> instance method of this object,
supplying the array of objects to be formatted into the
message.

<P CLASS=para>
The message or pattern string used by the
<tt CLASS=literal>MessageFormat</tt> should contain digits enclosed in
curly braces to indicate where each argument should be
substituted.  The sequence "<tt CLASS=literal>{0}</tt>" indicates that the
first object should be converted to a string (if necessary)
and inserted at that point, while the sequence "<tt CLASS=literal>{3}</tt>"
indicates that the fourth object should be inserted, for
example.  If the object to be inserted is not a string,
<tt CLASS=literal>MessageFormat</tt> checks to see if it is a <tt CLASS=literal>Date</tt>
or a subclass of <tt CLASS=literal>Number</tt>.  If so, it uses a default
<tt CLASS=literal>DateFormat</tt> or <tt CLASS=literal>NumberFormat</tt> object to convert
the value to a string.  If not, it simply invokes the
object's <tt CLASS=literal>toString()</tt> method to convert it.

<P CLASS=para>
A digit within curly braces in a pattern string may be
optionally followed by a comma, and one of the words "date",
"time", "number", or "choice", to indicate that the
corresponding argument should be formatted as a date, time,
number, or choice before being substituted into the pattern
string.  Any of these keywords may additionally be followed
by a comma and additional pattern information to be used in
formatting the date, time, number, or choice.  (See
<tt CLASS=literal>SimpleDateFormat</tt>, <tt CLASS=literal>DecimalFormat</tt>, and
<tt CLASS=literal>ChoiceFormat</tt> for more information.)

<P CLASS=para>
You can use the <tt CLASS=literal>setLocale()</tt> method to specify a
non-default <tt CLASS=literal>Locale</tt> that the <tt CLASS=literal>MessageFormat</tt>
should use when obtaining <tt CLASS=literal>DateFormat</tt> and
<tt CLASS=literal>NumberFormat</tt> objects to format dates, time, and
numbers inserted into the pattern.

<P CLASS=para>
You can change the <tt CLASS=literal>Format</tt> object used at a
particular position in the pattern with the
<tt CLASS=literal>setFormat()</tt> method.  You can set a new pattern for
the <tt CLASS=literal>MessageFormat</tt> object by calling
<tt CLASS=literal>applyPattern()</tt>, and you can obtain a string that
represents the current formatting pattern by calling
<tt CLASS=literal>toPattern()</tt>.

<P CLASS=para>
<tt CLASS=literal>MessageFormat</tt> also supports a <tt CLASS=literal>parse()</tt> method
that can parse an array of objects out of a specified
string, according to the specified pattern.

<DIV CLASS=screen>
<P>
<PRE>
public class <tt CLASS=literal>MessageFormat</tt> extends Format {
    // <tt CLASS=literal>Public Constructor</tt>
            public <tt CLASS=literal>MessageFormat</tt>(String <tt CLASS=literal>pattern</tt>);
    // <tt CLASS=literal>Class Methods</tt>
            public static String <tt CLASS=literal>format</tt>(String <tt CLASS=literal>pattern</tt>, Object[] <tt CLASS=literal>arguments</tt>);
    // <tt CLASS=literal>Public Instance Methods</tt>
            public void <tt CLASS=literal>applyPattern</tt>(String <tt CLASS=literal>newPattern</tt>);
            public Object <tt CLASS=literal>clone</tt>();  //<tt CLASS=literal> Overrides Format</tt>
            public boolean <tt CLASS=literal>equals</tt>(Object <tt CLASS=literal>obj</tt>);  //<tt CLASS=literal> Overrides Object</tt>
            public final StringBuffer <tt CLASS=literal>format</tt>(Object[] <tt CLASS=literal>source</tt>, StringBuffer <tt CLASS=literal>result</tt>, FieldPosition <tt CLASS=literal>ignore</tt>);
            public final StringBuffer <tt CLASS=literal>format</tt>(Object <tt CLASS=literal>source</tt>, StringBuffer <tt CLASS=literal>result</tt>, FieldPosition <tt CLASS=literal>ignore</tt>);  //<tt CLASS=literal> Defines Format</tt>
            public Format[] <tt CLASS=literal>getFormats</tt>();
            public Locale <tt CLASS=literal>getLocale</tt>();
            public int <tt CLASS=literal>hashCode</tt>();  //<tt CLASS=literal> Overrides Object</tt>
            public Object[] <tt CLASS=literal>parse</tt>(String <tt CLASS=literal>source</tt>, ParsePosition <tt CLASS=literal>status</tt>);
            public Object[] <tt CLASS=literal>parse</tt>(String <tt CLASS=literal>source</tt>) throws ParseException;
            public Object <tt CLASS=literal>parseObject</tt>(String <tt CLASS=literal>text</tt>, ParsePosition <tt CLASS=literal>status</tt>);  //<tt CLASS=literal> Defines Format</tt>
            public void <tt CLASS=literal>setFormat</tt>(int <tt CLASS=literal>variable</tt>, Format <tt CLASS=literal>newFormat</tt>);
            public void <tt CLASS=literal>setFormats</tt>(Format[] <tt CLASS=literal>newFormats</tt>);
            public void <tt CLASS=literal>setLocale</tt>(Locale <tt CLASS=literal>theLocale</tt>);
            public String <tt CLASS=literal>toPattern</tt>();
}
</PRE>
</DIV>

</DIV>

<DIV CLASS=sect2>
<h3 CLASS=sect2><A CLASS="TITLE" NAME="JNUT2-CH-29-SECT-13.2">Hierarchy:</A></h3>

<P CLASS=para>
Object->Format(Serializable, Cloneable)->MessageFormat

</DIV>

</DIV>


<DIV CLASS=htmlnav>

<P>
<HR align=left width=515>
<table width=515 border=0 cellpadding=0 cellspacing=0>
<tr>
<td width=172 align=left valign=top><A HREF="ch29_12.htm"><IMG SRC="gifs/txtpreva.gif" ALT="Previous" border=0></A></td>
<td width=171 align=center valign=top><a href="index.htm"><img src='gifs/txthome.gif' border=0 alt='Home'></a></td>
<td width=172 align=right valign=top><A HREF="ch29_14.htm"><IMG SRC="gifs/txtnexta.gif" ALT="Next" border=0></A></td>
</tr>
<tr>
<td width=172 align=left valign=top>java.text.Format (JDK 1.1)</td>
<td width=171 align=center valign=top><a href="index/idx_0.htm"><img src='gifs/index.gif' alt='Book Index' border=0></a></td>
<td width=172 align=right valign=top>java.text.NumberFormat (JDK 1.1)</td>
</tr>
</table>
<hr align=left width=515>

<IMG SRC="gifs/smnavbar.gif" USEMAP="#map" BORDER=0> 
<MAP NAME="map"> 
<AREA SHAPE=RECT COORDS="0,0,108,15" HREF="../javanut/index.htm"
alt="Java in a Nutshell"> 
<AREA SHAPE=RECT COORDS="109,0,200,15" HREF="../langref/index.htm" 
alt="Java Language Reference"> 
<AREA SHAPE=RECT COORDS="203,0,290,15" HREF="../awt/index.htm" 
alt="Java AWT"> 
<AREA SHAPE=RECT COORDS="291,0,419,15" HREF="../fclass/index.htm" 
alt="Java Fundamental Classes"> 
<AREA SHAPE=RECT COORDS="421,0,514,15" HREF="../exp/index.htm" 
alt="Exploring Java"> 
</MAP>
</DIV>

</BODY>
</HTML>
